fix(wr-agent): a resolve answers at a deadline, so a hung mount can't hold a read slot (#334) - #346

Summary

Closes #334.

A remote cmd-click on link/../file.rb makes the agent's File service resolve the path on the host (#327). If the link leads onto a hung NFS or FUSE mount, canonicalize blocks for as long as the mount does. The request thread held one of the four read slots and a permit the whole time, so four clicks left every file read on the host Busy until the agent restarted.

wr-agent

• The deadline. resolve runs its walk on its own thread (with_deadline) and answers after 10 seconds whether or not the walk has returned. The answer is an Io timeout with a fixed prefix, RESOLVE_TIMED_OUT. Its request thread holds its read slot and permit until the reply is written, and a hung walk holds neither, so reads and idle exit carry on.
• The cap. Walks left behind are counted exactly once in ABANDONED_WALKS, using a per-walk state word, and a panic in the walk still updates the count. Once four are counted, resolve answers Busy without starting another. Up to seven can be parked, since walks already waiting can still be left behind.
• Hand-off. hand_off is refused while any walk is left behind. A FUSE request the daemon has already read waits uninterruptibly (request_wait_answer in Linux's fs/fuse/dev.c), and execve waits for every other thread to die, so the hand-off would freeze every session on the host. That keeps the behaviour the held permit used to give. The check is race-free: with Quiet held, no request starts.
• Thread start. The walk thread starts through thread::Builder, so if the OS refuses a thread the answer is Busy instead of a panic.
• Logging. The agent logs each walk it leaves behind and each one that returns.

macapp

• A click stops at the first resolve that times out (AgentFileProvider.resolveTimedOut). Its other candidates resolve the same prefix, or would read through the same link with no deadline, so nothing more in that click reaches the host. One click on a dead mount therefore costs 10 seconds and one walk, instead of up to 40 seconds and four walks.

Docs: docs/designs/remote-workrooms.md "Path handling" and the hand-off section cover:

• the deadline, the cap and the hand-off refusal;
• what a remote host shows while a walk is stuck: each connect pushes the update again and is refused, logged only;
• that restarting the agent can't clear a walk parked in a FUSE wait;
• the known limits, wr-agent read through a link onto a hung mount holds a read slot and permit forever #343 and A remote cmd-click whose :line comes before its .. loses its healthy variant when the resolve times out #345.

Follow-ups filed (all part of #154):

• wr-agent read through a link onto a hung mount holds a read slot and permit forever #343: read has no deadline. A plain link/file.rb click onto a hung mount still holds a read slot forever. This is the most exploitable remaining finding.
• A remote cmd-click that times out on a hung mount shows the user nothing #344: a timed-out click shows the user nothing.
• A remote cmd-click whose :line comes before its .. loses its healthy variant when the resolve times out #345: a word whose :line comes before its .. (good.rb:12/link/../t.rb) loses its healthy good.rb variant when the resolve times out.

Accepted trade-offs from the adversarial review:

• The abandoned-walk count is per agent, so one workroom's dead link affects every workroom on that host.
• The hand-off refusal also covers mounts whose waits are killable, such as NFS hard mounts, because userspace can't tell those apart from FUSE.

Test Coverage

CODE PATHS (vcs/crates/wr-agent/src/file.rs, handoff.rs)
- resolve: invalid relative path rejected before any I/O        [★★ TESTED]
- resolve: Busy at MAX_ABANDONED_WALKS                          [★★ TESTED] a_resolve_is_refused_busy_while_too_many_earlier_walks_are_still_out
- with_deadline: answers in time                                [★★ TESTED]
- with_deadline: timeout, walk left behind, Io "resolving timed out", count +1   [★★★ TESTED]
- with_deadline: a late walk takes the count back once          [★★★ TESTED]
- walks_left_behind() reflects the count                        [★★ TESTED]
- catch_unwind: panic before the deadline -> Io "panicked"      [★★★ TESTED]
- catch_unwind: panic after the deadline still leaves the count [★★★ TESTED]
- timeout branch "finished in the meantime" race arm            [GAP] intentionally untested: needs a production hook
- Disconnected arm                                              [GAP] intentionally untested: unreachable under catch_unwind
- Builder::spawn failure -> Busy                                [GAP] intentionally untested: the OS refusing a thread can't be forced
- hand_off refuses while walks_left_behind() > 0                [GAP] intentionally untested: needs a live serve context and a hung mount; checked by reading

CODE PATHS (macapp)
- remoteFile: a resolve timeout ends the click                  [★★★ TESTED] testARemoteParentTraversalIsResolvedOnTheHost (mutation-checked)

• Coverage gate: 67% value-weighted. The 4 paths above are marked intentionally untested by the owner, each with its reason.
• Test value: 2 tests written, 4 rejected by the authoring gate, 1 existing test extended, 0 paths weakly covered. The review rounds added the deadline, cap and stop-rule tests.
• Every new test was checked red against a mutation of the code it covers:
  • the cap check removed;
  • the abandoned walk not counted;
  • with_deadline waiting for the walk (fails in 7 s, it doesn't hang);
  • catch_unwind removed;
  • walks_left_behind() returning 0;
  • the stop rule disabled.
• The Rust deadline test asserts the literal "resolving timed out" that the app matches.
• Base control: unavailable (no package.json ecosystem).

Pre-Landing Review

Before /ship: the independent adversarial pass that macapp/AGENTS.md rule 3 requires for any wr-agent change found five issues, all fixed. The serious one: a hand-off could execve behind an uninterruptible FUSE walk and freeze every session. The other four:

• the cap was overstated;
• a thread that failed to start would panic;
• one test would have hung instead of failing;
• the read-cap test could have passed for the wrong reason.

/ship review: this ran past the skill's 3-round fix limit, with the owner approving each extra round. The review log records cycles: 5, converged: false.

• Round 1 (specialists + Red Team; performance and security found nothing):
  • a click stops at the first resolve timeout. Without this, one click on a dead mount could cost up to 40 s and four walks;
  • comments now say slots are held until the reply is written;
  • the hand-off docs list the new refusal and its effect on a remote host;
  • kept, at the owner's call: counting abandoned walks rather than live ones (simplification advisory).
• Rounds 2–3: comment and doc corrections only.
• After Step 11: the click-stop rule was narrowed to "skip only the same prefix", following Codex's P2. The lean re-review found that narrowing let a candidate with no .. read through the hung link with no deadline, so it was reverted to "a timeout ends the click" at the owner's call. The lost-click case is filed as A remote cmd-click whose :line comes before its .. loses its healthy variant when the resolve times out #345.
• Review binding: the final tree differs from the last fully reviewed tree (bdaf2a3c) only by the log lines, which the lean re-review covered, and by comment, doc and TODO wording.

Step 11 adversarial:

• Claude: findings filed as wr-agent read through a link onto a hung mount holds a read slot and permit forever #343 and A remote cmd-click that times out on a hung mount shows the user nothing #344; the restart-docs and logging items were fixed.
• Codex adversarial: one P2, which led to A remote cmd-click whose :line comes before its .. loses its healthy variant when the resolve times out #345.
• Codex structured: missing coverage. It concluded "No actionable regressions found" but without the required marker, so the P1 gate wasn't established.

Exploratory QA

Functional surface: the wr-agent File service resolve.

• Probe 1: the resolve tests pass 6/6.
• Probe 2: the deadline, cap and panic edge cases pass 19/19.
• Verdict: PASS.
• Limit: no real hung NFS or FUSE mount was available. The deadline is driven with a blocked walk through with_deadline, and the hand-off refusal was checked by reading the code.

Design Review

No frontend files changed — design review skipped.

Eval Results

No prompt-related files changed — evals skipped.

Scope Drift

Scope Check: CLEAN. Beyond #334:

• the app-side stop rule, which the review asked for;
• a P0 TODO for a relay test that flaked under load and is unrelated to this branch.

Plan Completion

No plan file detected. The plan was #334's "How to fix", the request, and the independent review's findings: 12 items, 9 DONE, 1 CHANGED. The CHANGED item: it detaches the walk (#334's first option) rather than walking components one at a time with openat. 2 items the diff can't show were confirmed by evidence:

• the FUSE kernel behaviour, from fs/fuse/dev.c fetched from torvalds/linux;
• the independent review, from its report, with its findings in the diff.

Verification Results

No plan-specific verification items. Automatic diff-scoped QA is above.

TODOS

No TODO items completed in this PR. Added one P0: a_relay_with_no_agent_fails_fast_and_says_so flaked once while the full Swift suite ran alongside it. It passed 5/5 alone, and this branch doesn't touch the relay.

Documentation

Status: current. No edits needed.

Scope: committed diff 4862781..b44aa65, with nothing staged, unstaged or untracked. Docs audited: README.md, CONTRIBUTING.md, AGENTS.md, macapp/AGENTS.md, macapp/README.md, docs/repository-notes.md, docs/designs/remote-workrooms.md and TODOS.md (read only). docs/agents, DESIGN.md, PRODUCT.md, the other docs/designs files and .agents/skills were searched for File service, hand-off refusal and remote cmd-click content, and none was affected.

Documentation health:

• docs/designs/remote-workrooms.md: current. The "Path handling" bullet (10s resolve deadline, abandoned-walk cap of 4 and the up-to-7 bound, hand-off refusal, click ends at the first timeout, wr-agent read through a link onto a hung mount holds a read slot and permit forever #343 and A remote cmd-click whose :line comes before its .. loses its healthy variant when the resolve times out #345 caveats), the hand-off prerequisite bullet and the "Known limits" retry note all match file.rs, handoff.rs, TerminalSessions.swift and AgentFileProvider.swift.
• README.md, CONTRIBUTING.md, AGENTS.md, macapp/AGENTS.md, macapp/README.md, docs/repository-notes.md: current. They mention the File service only generically, and none describes hand-off refusal reasons or remote cmd-click.
• TODOS.md: read only. The new wr-agent resolve through a link onto a dead mount holds a File read slot until the agent restarts #334 follow-up entry is parent-owned.

Coverage debt: #334 has reference and explanation coverage in remote-workrooms.md. There is no how-to or tutorial page, which is acceptable for an internal agent behaviour. No gaps were filled. No architecture diagrams are affected.

Test plan

• cargo test --manifest-path vcs/Cargo.toml --workspace: all suites pass on b44aa653 (run alone; see TODOS for the relay flake under parallel load)
• make app-test: full Swift unit suite passes on b44aa653
• cargo fmt --check, cargo clippy -D warnings, make app-lint: clean

🤖 Generated with Claude Code